Add SQL-Redis GEO and Date Query Support by nkanu17 · Pull Request #533 · redis/redis-vl-python

nkanu17 · 2026-03-16T17:22:56Z

Add SQL-Redis GEO and Date Query Support

Summary

Adds comprehensive GEO and Date query support to RedisVL's SQL interface via the sql-redis optional dependency.

Changes

Dependencies

Add sql-redis>=0.3.0 as optional dependency (pip install redisvl[sql-redis])

Documentation

Expanded SQL notebook (12_sql_to_redis_queries.ipynb) with:
- GEO queries using geo_distance() for radius filtering and distance calculations
- Date queries with ISO literals, BETWEEN, and date functions (YEAR(), MONTH(), DATE_FORMAT())
- Combined filters (GEO + TAG, GEO + NUMERIC, Date + TAG)
- Native GeoRadius filter examples for comparison
Updated docs/concepts/queries.md with SQL examples and link to guide

Example:

-- GEO: Find users within 50km of San Francisco
SELECT name FROM users WHERE geo_distance(location, POINT(-122.4194, 37.7749), 'km') < 50

-- Date: Filter by date range
SELECT name FROM events WHERE created_at BETWEEN '2024-01-01' AND '2024-03-31'

-- Date: Extract year and count
SELECT YEAR(created_at) AS year, COUNT(*) AS count FROM events GROUP BY year

GEO Query Support

Operators

Operator	SQL Example
`<`	`WHERE geo_distance(location, POINT(lon, lat), 'km') < 50`
`<=`	`WHERE geo_distance(location, POINT(lon, lat), 'km') <= 50`
`>`	`WHERE geo_distance(location, POINT(lon, lat), 'km') > 10`
`>=`	`WHERE geo_distance(location, POINT(lon, lat), 'km') >= 10`
`BETWEEN`	`WHERE geo_distance(location, POINT(lon, lat), 'km') BETWEEN 10 AND 50`

Units

Unit	Example
Kilometers	`geo_distance(location, POINT(-122.4, 37.8), 'km')`
Miles	`geo_distance(location, POINT(-122.4, 37.8), 'mi')`
Meters	`geo_distance(location, POINT(-122.4, 37.8), 'm')`
Feet	`geo_distance(location, POINT(-122.4, 37.8), 'ft')`

Distance Calculation in SELECT

SELECT name, geo_distance(location, POINT(-122.4194, 37.7749)) AS distance_meters
FROM stores

Combined Filters

-- GEO + TAG
WHERE category = 'retail' AND geo_distance(location, POINT(-122.4, 37.8), 'km') < 50

-- GEO + NUMERIC
WHERE age > 30 AND geo_distance(location, POINT(-122.4, 37.8), 'km') < 100

-- GEO + TEXT
WHERE description = 'engineer*' AND geo_distance(location, POINT(-87.6, 41.9), 'km') < 100

-- GEO + TAG + NUMERIC
WHERE job = 'engineer' AND age > 40 AND geo_distance(location, POINT(-87.6, 41.9), 'mi') < 50

Date Query Support

Operators with Date Literals

Operator	SQL Example
`>`	`WHERE created_at > '2024-01-01'`
`>=`	`WHERE created_at >= '2024-01-01'`
`<`	`WHERE created_at < '2024-12-31'`
`<=`	`WHERE created_at <= '2024-12-31'`
`=`	`WHERE created_at = '2024-01-01'`
`BETWEEN`	`WHERE created_at BETWEEN '2024-01-01' AND '2024-03-31'`

Date Functions in SELECT

Function	SQL Example	Redis Translation
`YEAR()`	`SELECT YEAR(created_at) AS year`	`APPLY year(@created_at) AS year`
`MONTH()`	`SELECT MONTH(created_at) AS month`	`APPLY monthofyear(@created_at) AS month`
`DAY()`	`SELECT DAY(created_at) AS day`	`APPLY dayofmonth(@created_at) AS day`
`DATE_FORMAT()`	`SELECT DATE_FORMAT(created_at, '%Y-%m-%d') AS date`	`APPLY timefmt(@created_at, "%Y-%m-%d") AS date`

Date Functions in WHERE

-- Filter by year
WHERE YEAR(created_at) = 2024

-- Filter by month
WHERE MONTH(created_at) >= 6

Date Functions in GROUP BY

SELECT YEAR(created_at) AS year, COUNT(*) AS count
FROM events
GROUP BY year
ORDER BY year DESC

Combined Filters

-- Date + TAG
WHERE category = 'meeting' AND created_at BETWEEN '2024-01-01' AND '2024-06-30'

-- Date + NUMERIC
WHERE priority > 5 AND created_at > '2024-01-01'

-- Date function + TAG
WHERE YEAR(created_at) = 2024 AND category = 'release'

Notes

Date literals (e.g., '2024-01-01') are automatically converted to Unix timestamps
GEO coordinates use POINT(longitude, latitude) format (lon first)
geo_distance() in SELECT returns distance in meters by default

Note

Medium Risk
Updates the optional sql-redis dependency and expands SQLQuery coverage to GEO and date/timestamp translation, which can affect query generation/compatibility for users enabling redisvl[sql-redis]. Risk is moderated by being optional and backed by new integration tests.

Overview
Expands SQLQuery capabilities (via sql-redis) to cover geographic and date/time querying. Documentation now includes examples for geo_distance() radius filters and distance calculations, ISO date literal filtering, and date functions like YEAR() plus grouping.

Bumps the optional dependency to sql-redis>=0.3.0, updates the SQL guide notebook with end-to-end GEO/date examples (including notes about GEO validation and coordinate order), and adds integration tests validating GEO filtering/selection translation (GEOFILTER/FT.AGGREGATE) and date literal + YEAR()/GROUP BY behavior.

^{Written by Cursor Bugbot for commit 99477b6. This will update automatically on new commits. Configure here.}

jit-ci · 2026-03-16T17:24:17Z

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

^{Security scan by Jit}

pyproject.toml

Copilot

Pull request overview

Adds GEO radius filtering and date/timestamp querying examples to RedisVL’s SQL interface (via the optional sql-redis dependency), along with integration tests and docs updates to demonstrate/validate the new query patterns.

Changes:

Bumps optional dependency sql-redis to >=0.3.0 (and includes it in the all extra).
Adds integration tests for geo_distance(...) queries and basic date literal / BETWEEN / YEAR() usage.
Expands SQL documentation and the SQL-to-Redis notebook with GEO and date query examples.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 6 comments.

File	Description
tests/integration/test_sql_redis_hash.py	Adds new integration coverage for GEO queries and date literal/date function patterns.
pyproject.toml	Bumps `sql-redis` optional dependency version; adds Hatch metadata setting.
docs/user_guide/12_sql_to_redis_queries.ipynb	Adds extensive GEO and date query tutorial content and examples.
docs/concepts/queries.md	Adds SQLQuery examples for aggregations, GEO, and date queries plus a link to the notebook.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

tests/integration/test_sql_redis_hash.py

docs/user_guide/12_sql_to_redis_queries.ipynb

pyproject.toml

Copilot

Pull request overview

Adds GEO radius and date/timestamp querying support to RedisVL’s SQL interface (via the optional sql-redis extra), along with expanded documentation and integration coverage to validate translation/execution behavior.

Changes:

Bump optional dependency to sql-redis>=0.3.0 (and update the all extra accordingly).
Add integration tests covering geo_distance() filters/aggregations and date literal/date function handling (e.g., BETWEEN, YEAR()).
Expand the SQL user guide notebook and concepts docs with GEO and date query examples.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

File	Description
tests/integration/test_sql_redis_hash.py	Adds integration tests for GEO and date SQL translation/execution.
pyproject.toml	Updates `redisvl[sql-redis]` extra to require `sql-redis>=0.3.0`.
docs/user_guide/12_sql_to_redis_queries.ipynb	Expands the SQL notebook with GEO/date sections and examples; updates outputs/metadata.
docs/concepts/queries.md	Adds SQL examples for aggregation, GEO, and date querying; links to the SQL notebook guide.

Comments suppressed due to low confidence (2)

docs/user_guide/12_sql_to_redis_queries.ipynb:762

The generated query/output uses the alias fist_value_age (missing the 'r' in 'first'). Even if it’s just an example, this typo propagates into the displayed Redis query and result keys; rename it to first_value_age in the SQL so the docs show the correct alias.

   "metadata": {},
   "source": [

docs/user_guide/12_sql_to_redis_queries.ipynb:179

The notebook still introduces a "Validate data entries on load" section, but the preceding SearchIndex.from_dict(...) examples no longer pass validate_on_load=True, so the narrative/example is inconsistent. Either re-add validate_on_load=True in the index construction snippets or adjust the section text to explain that validation is disabled in this guide and how to enable it if desired.

   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Bring your own Redis connection instance\n",

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

docs/user_guide/12_sql_to_redis_queries.ipynb

Copilot

Pull request overview

Adds GEO and date/time query support coverage for RedisVL’s SQLQuery path (via the optional sql-redis dependency), along with expanded documentation and integration tests to validate new SQL-to-Redis translations.

Changes:

Bump optional dependency sql-redis to >=0.3.0 (and update the all extra).
Add integration tests for geo_distance() filters/SELECT distance and date literals + YEAR() + GROUP BY.
Expand SQL user guide notebook and concepts docs with GEO/date examples and summaries.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 3 comments.

File	Description
`tests/integration/test_sql_redis_hash.py`	Adds new integration fixtures + tests covering GEO radius filters, `geo_distance()` in SELECT (aggregate), ISO date literals, `YEAR()` extraction, and grouping.
`pyproject.toml`	Updates the `sql-redis` optional extra (and `all`) to require `>=0.3.0`.
`docs/user_guide/12_sql_to_redis_queries.ipynb`	Major expansion of the SQL guide with GEO + date querying examples, plus native GEO filter comparisons.
`docs/concepts/queries.md`	Adds SQLQuery examples for aggregations, GEO, and date queries, and links to the expanded notebook.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

docs/user_guide/12_sql_to_redis_queries.ipynb

tests/integration/test_sql_redis_hash.py

justin-cechmanek

LGTM

docs/user_guide/12_sql_to_redis_queries.ipynb

Copilot

Pull request overview

Adds GEO distance querying and date/timestamp querying support to RedisVL’s SQL interface by upgrading the optional sql-redis translator dependency and expanding docs/examples and integration coverage.

Changes:

Bump optional dependency sql-redis to >=0.3.0.
Add new SQLQuery integration tests for GEO radius filtering and date literal / YEAR() behavior.
Expand SQL-to-Redis notebook and concepts docs with GEO and date query examples.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

File	Description
`tests/integration/test_sql_redis_hash.py`	Adds GEO and date/timestamp integration tests for SQLQuery translation/execution.
`pyproject.toml`	Updates `sql-redis` optional dependency (and `all`) to `>=0.3.0`.
`docs/user_guide/12_sql_to_redis_queries.ipynb`	Extends the SQL guide with GEO and date examples, plus native Geo filter comparisons.
`docs/concepts/queries.md`	Adds SQL examples for aggregations, GEO, date functions, and links to the SQL guide.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

tests/integration/test_sql_redis_hash.py

Copilot

Pull request overview

This PR expands RedisVL’s SQLQuery integration (via the optional sql-redis dependency) to cover GEO distance queries and date/timestamp literals/functions, and documents these capabilities with updated guides and examples.

Changes:

Bump optional dependency to sql-redis>=0.3.0 (including redisvl[all]).
Add integration tests for geo_distance() filters/SELECT projections and date literal/function handling (e.g., YEAR(), BETWEEN, GROUP BY).
Expand the SQL-to-Redis user guide notebook and add SQL examples to the queries concept doc.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 3 comments.

File	Description
tests/integration/test_sql_redis_hash.py	Adds GEO and date/timestamp SQLQuery integration tests.
pyproject.toml	Updates optional dependency minimum version for `sql-redis`.
docs/user_guide/12_sql_to_redis_queries.ipynb	Extends the SQL guide with GEO + date examples and translations.
docs/concepts/queries.md	Adds SQLQuery examples for aggregations, GEO, date queries, and vector params, plus a link to the notebook.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

docs/user_guide/12_sql_to_redis_queries.ipynb

Copilot

Pull request overview

Adds GEO-radius and date/timestamp query support examples to RedisVL’s SQL interface by bumping the optional sql-redis dependency and extending integration tests/docs to cover geo_distance() and date literals/functions.

Changes:

Bump optional dependency to sql-redis>=0.3.0 (and align all extra accordingly).
Add integration tests for GEO distance filtering/selection and date literal + YEAR() usage (including GROUP BY).
Expand SQLQuery documentation/examples in the SQL notebook and query concepts page.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

File	Description
`tests/integration/test_sql_redis_hash.py`	Adds GEO and date/timestamp integration coverage for SQLQuery translation/execution.
`pyproject.toml`	Updates optional dependency constraints for `sql-redis` (and `all` extra).
`docs/user_guide/12_sql_to_redis_queries.ipynb`	Expands the SQL-to-Redis guide with GEO + date query patterns and examples.
`docs/concepts/queries.md`	Adds SQLQuery examples for aggregations, GEO, and date queries + link to the notebook.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

pyproject.toml

 sql-redis = [
-    "sql-redis>=0.2.0",
+    "sql-redis>=0.3.0",
 ]


docs/user_guide/12_sql_to_redis_queries.ipynb

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

docs/user_guide/12_sql_to_redis_queries.ipynb

Add sql-redis optional dependency

169e1fc

Copilot AI review requested due to automatic review settings March 16, 2026 17:22

Copilot started reviewing on behalf of nkanu17 March 16, 2026 17:23 View session

cursor bot reviewed Mar 16, 2026

View reviewed changes

pyproject.toml Outdated Show resolved Hide resolved

nkanu17 requested a review from rbs333 March 16, 2026 17:27

Copilot AI reviewed Mar 16, 2026

View reviewed changes

nkanu17 force-pushed the feat/sql-redis-geo-date branch from 3393fdc to 81e558b Compare March 16, 2026 17:30

Copilot AI review requested due to automatic review settings March 16, 2026 17:31

nkanu17 force-pushed the feat/sql-redis-geo-date branch from 81e558b to e454e0d Compare March 16, 2026 17:31

Copilot started reviewing on behalf of nkanu17 March 16, 2026 17:32 View session

nkanu17 force-pushed the feat/sql-redis-geo-date branch 2 times, most recently from 3cd52a0 to 7358866 Compare March 16, 2026 17:35

Copilot AI reviewed Mar 16, 2026

View reviewed changes

docs/user_guide/12_sql_to_redis_queries.ipynb Show resolved Hide resolved

nkanu17 added 2 commits March 16, 2026 13:37

Add GEO and Date query examples to SQL notebook

36decdf

Expand SQL section in queries concept doc with link to guide

82cd5dd

nkanu17 force-pushed the feat/sql-redis-geo-date branch from 7358866 to 3bcedd0 Compare March 16, 2026 17:37

nkanu17 requested review from Copilot and justin-cechmanek March 16, 2026 17:42

nkanu17 force-pushed the feat/sql-redis-geo-date branch from 3bcedd0 to 3d2af53 Compare March 16, 2026 17:43

Copilot started reviewing on behalf of nkanu17 March 16, 2026 17:44 View session

cursor bot reviewed Mar 16, 2026

View reviewed changes

docs/user_guide/12_sql_to_redis_queries.ipynb Show resolved Hide resolved

Copilot AI reviewed Mar 16, 2026

View reviewed changes

docs/user_guide/12_sql_to_redis_queries.ipynb Show resolved Hide resolved

docs/user_guide/12_sql_to_redis_queries.ipynb Show resolved Hide resolved

docs/user_guide/12_sql_to_redis_queries.ipynb Outdated Show resolved Hide resolved

justin-cechmanek reviewed Mar 16, 2026

View reviewed changes

tests/integration/test_sql_redis_hash.py Outdated Show resolved Hide resolved

justin-cechmanek approved these changes Mar 16, 2026

View reviewed changes

rbs333 approved these changes Mar 16, 2026

View reviewed changes

rbs333 reviewed Mar 16, 2026

View reviewed changes

docs/user_guide/12_sql_to_redis_queries.ipynb Show resolved Hide resolved

nkanu17 force-pushed the feat/sql-redis-geo-date branch from 3d2af53 to 01936fd Compare March 16, 2026 20:00

Copilot AI review requested due to automatic review settings March 16, 2026 20:01

nkanu17 force-pushed the feat/sql-redis-geo-date branch from 01936fd to ca042d7 Compare March 16, 2026 20:01

Copilot started reviewing on behalf of nkanu17 March 16, 2026 20:02 View session

nkanu17 force-pushed the feat/sql-redis-geo-date branch 2 times, most recently from 5808689 to c99c943 Compare March 16, 2026 20:06

Copilot AI reviewed Mar 16, 2026

View reviewed changes

tests/integration/test_sql_redis_hash.py Show resolved Hide resolved

tests/integration/test_sql_redis_hash.py Show resolved Hide resolved

nkanu17 force-pushed the feat/sql-redis-geo-date branch from c99c943 to 45e2566 Compare March 16, 2026 20:10

Copilot AI review requested due to automatic review settings March 16, 2026 20:13

nkanu17 force-pushed the feat/sql-redis-geo-date branch from 45e2566 to f1dc967 Compare March 16, 2026 20:13

Copilot started reviewing on behalf of nkanu17 March 16, 2026 20:14 View session

nkanu17 force-pushed the feat/sql-redis-geo-date branch from f1dc967 to 54b8c78 Compare March 16, 2026 20:15

Copilot AI reviewed Mar 16, 2026

View reviewed changes

docs/user_guide/12_sql_to_redis_queries.ipynb Show resolved Hide resolved

docs/user_guide/12_sql_to_redis_queries.ipynb Show resolved Hide resolved

docs/user_guide/12_sql_to_redis_queries.ipynb Show resolved Hide resolved

nkanu17 force-pushed the feat/sql-redis-geo-date branch from 54b8c78 to f8238a1 Compare March 16, 2026 20:20

Copilot AI review requested due to automatic review settings March 16, 2026 20:30

nkanu17 force-pushed the feat/sql-redis-geo-date branch from f8238a1 to 2c0e279 Compare March 16, 2026 20:30

Copilot started reviewing on behalf of nkanu17 March 16, 2026 20:30 View session

Copilot AI reviewed Mar 16, 2026

View reviewed changes

pyproject.toml

Comment on lines 56 to 58

sql-redis = [

"sql-redis>=0.2.0",

"sql-redis>=0.3.0",

]

docs/user_guide/12_sql_to_redis_queries.ipynb Outdated Show resolved Hide resolved

cursor bot reviewed Mar 16, 2026

View reviewed changes

docs/user_guide/12_sql_to_redis_queries.ipynb Show resolved Hide resolved

Add GEO and Date SQL integration tests

99477b6

nkanu17 force-pushed the feat/sql-redis-geo-date branch from 2c0e279 to 99477b6 Compare March 16, 2026 20:35

nkanu17 merged commit b8c234f into main Mar 16, 2026
66 checks passed

Conversation

nkanu17 commented Mar 16, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add SQL-Redis GEO and Date Query Support

Summary

Changes

Dependencies

Documentation

Example:

GEO Query Support

Operators

Units

Distance Calculation in SELECT

Combined Filters

Date Query Support

Operators with Date Literals

Date Functions in SELECT

Date Functions in WHERE

Date Functions in GROUP BY

Combined Filters

Notes

Uh oh!

jit-ci bot commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛡️ Jit Security Scan Results

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

justin-cechmanek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

cursor bot left a comment

nkanu17 commented Mar 16, 2026 •

edited by cursor bot

Loading

jit-ci bot commented Mar 16, 2026 •

edited

Loading